The install command dynamically loads defined routines from an object file. The user decides on the internal name of the routine but the internal name must consist of lower case letters only. The object file is an object compiled by the C or FORTRAN compiler. On IRIX, the object must be compiled with the option -G 0 given to either the C or FORTRAN compiler. The rtn-name is the name of one of the procedure(s) or function(s) the user wants to install from the object file. The routine will be installed as name and as a procedure (not returning value) or as a function (returning value) depending on the name separator being a : (colon) or a = (equal sign) respectively. (See example below).
NOTE: This option is only available on IRIX and SUNOS for the moment.
The external routine must expect pointers to double for all its arguments. Thus, all arguments are passed by pointers except that pointers to variables do not point to the variables as such but to a temporary copy of them. This allows us to have expressions like
f = mycall(X, sin(x) + 1, data)
for which the value sin(x) + 1 must necessarily be a temporary copy. In this example, the prototype is a function mycall(VEC, expr, expr). We shall consider an example in more detail below. All arguments are strongly typed as vector, parameter, expression or string. Prototyping is done using the uppercase-lowercase convention. Parameters are prototyped using the word PARAM or less (e.g. PAR).
On IRIX, the linker will create a binary file built from the module name and with the extension file.ld. This binary is the one that will be loaded in memory. Time stamps are included so that ld(1) will not be called if not necessary. These files are not erased at exit, since they are reusable and prevent the linker to be called if nothing changed between two sessions of .
Successive calls of install with the same module should not be done unless the same functions and procedures are reinstalled. If this is the case, the user should then reinstall the same modules (that could have been modified and recompiled in the mean time) using the reinstall command. If a module is reinstalled with different routines or function or procedure names, the previously defined functions or procedures might not be properly installed anymore and calling them might result in an undefined behavior.
The file fudgit.h describes the functions user-defined programs can linked with. Among other things, these functions allow the user to have elegant error handling and exit.
The show table command can be used to list all the installed objects at a given time.
A file having the same base name of the module but with the extension libs can be put in the same directory in order to include extra libraries while loading the module. On IRIX, these extra libraries must all contain objects compiled with the flag -G 0 (see cc(1)). (For example, some IRIX systems have a -lm_G0 math library.) User-defined libraries can be specified along with system libraries. A typical example could be a line like:
/home/myname/myproject/libmyG0.a /usr/lib/libmG0.a
for linking with user's library /home/myname/myproject/libmyG0.a. Equivalently, for non-IRIX systems, loading a FORTRAN object might require something like this:
/usr/lib/libF77.a /usr/lib/libm.a
Library names can be on multiple lines. However, the file cannot have more than 1024 bytes. A `#' found anywhere in this file will make the rest of the file to be ignored.
Note that when loading FORTRAN code, the user must append an underscore to the routine name so that install or reinstall can find it.
The IRIX version does not fully support incremental linking, i.e., to use, in an object to be installed, symbols that were defined in previously installed objects. However, all the symbols contained in the original executable remain at all time available to all linked routines. Therefore, IRIX users should make sure that external objects are self-contained and only reference to external routines that are intrinsic to or come directly (and once) from linked libraries at installation time.
install object-file rtn-name[:|=]name(arg-list)...
hostname: cat mymodule.c #include <math.h> #include "fudgit.h" /* An example of a user-defined routine inversing the order of an even * vector. Typical call would be: * myproc(A_VEC, data) * from C-calculator mode. NOTE that both VEC and expr are pointers. * To make things explicit, fudgit.h contains a few typedef's. */ void myproc(X, dn) VEC X; expr dn; { int i, half_n; int n = (int)*dn; /* note that dn is a pointer to a double */ double tmp; if (n%2 == 1) /* report error if odd number (Why not?)*/ Ft_matherror("%s: Called with an odd number %d.", "myproc", n); /* You have full use of math and stdio libraries too!!! */ fprintf(stderr, "BTW, Did you know that %lf is the sqrt(pi)?\n", sqrt(M_PI)); half_n = n >>1; /* half of n */ for (i=0;i<half_n;i++) { /* Standard C: indices from 0 to data-1 */ tmp = X[i]; X[i] = X[n-i]; X[n-i] = tmp; } } /* * Another example involving a function. The following calculates the * non-normalized correlation between vectors A and B as defined by * corr(A, B) = <A*B> - <A> * <B> * */ double myfunc(A, B, dn) VEC A, B; expr dn; { int i, n = (int)*dn; /* Again, dn is a pointer to a double */ double sumA, sumB, sumAB; sumA = sumB = sumAB = 0.0; /* sum up the values of interest */ for (i=0;i<n; i++) { /* indices go from 0 to data-1 */ sumA += A[i]; sumB += B[i]; sumAB += A[i] * B[i]; } /* leave it simple */ sumA /= *dn; sumB /= *dn; sumAB /= *dn; return (sumAB - sumA*sumB); } hostname: cc -G 0 -O -c mymodule.c hostname: cat loadex.ft # This is an example for loading # Install function myfunc as corr() and procedure myproc as inverse() # Prototypes are made from any name representing the proper type: install mymodule.o myproc:inverse(V, n) myfunc=corr(V, V, n) set data 24 let x=1;X=x++ let Y=sin(X) cmode # Inverse order of vector X inverse(X, data) # Calculate correlation between X and Y y=corr(X, Y, data) # Print its value "correlation:", y fmode hostname: fudgit loadex.ft install: myproc installed as procedure inverse. install: myfunc installed as function corr. BTW, Did you know that 1.772454 is the sqrt(pi)? correlation: 9.20717026e-01
When linking FORTRAN functions or subroutines, the user must append an underscore after every function or subroutine name. All argument variables and vectors have to be defined double precision as well as returning functions. Typical examples are included in the distribution in the tools directory.
C, cmode, show table, func, proc